Entity Attributes

The state of fields and JavaBeans properties of entities are generally persisted with the entity instance. These persistent things are called attributes.

JPA Attributes are subdivided into two main types: singular and plural. Singular attributes are scalar types like Integer or String. Plural attributes are collection values, such as List<Integer> or Set<String>.

The values of singular attributes (and the elements of plural attributes) can be of any application-defined entity type or a JPA Basic type. The JPA basic types are all of the Java primitive types, all boxed primitives, enums, BigInteger, BigDecimal, String, Date (java.util.Date or java.sql.Date), Time, and Timestamp.

You can direct JPA to read and write your entity's attributes by direct field access or via JavaBeans property access methods (that is, "getters and setters"). Direct field access is the default. To request property access, annotate the class with @Access(AccessType.PROPERTY). If using direct field access, attribute-specific JPA annotations should be on the fields themselves; when using property access, the attribute-specific annotations should be on the getter method for that property.

ID Attributes and Auto-Generated Identifiers

Each entity class must have exactly one ID attribute. The value of this attribute together with the fully-qualified class name uniquely identifies an instance to the entity manager.

ID values can be assigned by the application, or they can be generated by the JPA entity manager. To declare a generated identifier, annotate the field with @GeneratedValue. To declare an application-assigned identifier, leave off the @GeneratedValue annotation.

Generated identifier fields must not be initialized or modified by application code. Application-assigned identifier fields must be initialized to a unique value before the entity is persisted by the entity manager, but must not be modified afterward.

Single-valued Attributes

By default, every field of a JPA basic type is a persistent attribute. If a basic type field should not be presistent, mark it with transient or annotate it with @Transient.

Single-valued attributes of entity types must be annotated with @OneToOne or @ManyToOne.

Single-valued types that are neither entity types nor JPA Basic types are not presently supported by Errai JPA. Such attributes must be marked transient.

Here is an example of an entity with single-valued basic attributes and a single-valued relation to another entity type:

@Entity
public class Album {

  @GeneratedValue
  @Id
  private Long id;

  private String name;

  @ManyToOne
  private Artist artist;

  private Date releaseDate;

  private Format format;

  public Long getId() { return id; }
  public void setId(Long id) { this.id = id; }

  public String getName() { return name; }
  public void setName(String name) { this.name = name; }

  public Artist getArtist() { return artist; }
  public void setArtist(Artist artist) { this.artist = artist; }

  public Date getReleaseDate() { return releaseDate; }
  public void setReleaseDate(Date releaseDate) { this.releaseDate = releaseDate; }

  public Format getFormat() { return format; }
  public void setFormat(Format format) { this.format = format; }
}

Plural (collection-valued) Attributes

Collection-valued types Collection<T>, Set<T>, and List<T> are supported. JPA rules require that all access to the collections are done through the collection interface method; never by specific methods on an implementation.

The element type of a collection attribute can be a JPA basic type or an entity type. If it is an entity type, the attribute must be annotated with @OneToMany or @ManyToMany.

Here is an example of an entity with two plural attributes:

@Entity
public class Artist {

  @Id
  private Long id;

  private String name;

  // a two-way relationship (albums refer back to artists)
  @OneToMany(mappedBy="artist", cascade=CascadeType.ALL)
  private Set<Album> albums = new HashSet<Album>();

  // a one-way relationship (genres don't reference artists)
  @OneToMany(cascade={CascadeType.PERSIST, CascadeType.MERGE})
  private Set<Genre> genres = new HashSet<Genre>();

  public Long getId() { return id; }
  public void setId(Long id) { this.id = id; }

  public String getName() { return name; }
  public void setName(String name) { this.name = name; }

  public Set<Album> getAlbums() { return albums; }
  public void setAlbums(Set<Album> albums) { this.albums = albums; }

  public Set<Genre> getGenres() { return genres; }
  public void setGenres(Set<Genre> genres) { this.genres = genres; }
}

Cascade Rules

When an entity changes state (more on this later), that state change can be cascaded automatically to related entity instances. By default, no state changes are cascaded to related entities. To request cascading of entity state changes, use the cascade attribute on any of the relationship quantifiers @OneToOne, @ManyToOne, @OneToMany, and @ManyToMany.

For an example of specifying cascade rules, refer to the Artist example above. In that example, the cascade type on albums is ALL. When a particular Artist is persisted or removed, detached, etc., all of that artist's albums will also be persisted or removed, or detached correspondingly. However, the cascade rules for genres are different: we only specify PERSIST and MERGE. Because a Genre instance is reusable and potentially shared between many artists, we do not want to remove or detach these when one artist that references them is removed or detached. However, we still want the convenience of automatic cascading persistence in case we persist an Artist which references a new, unmanaged Genre.

Storing and Updating Entities

To store an entity object in persistent storage, pass that object to the EntityManager.persist() method. Once this is done, the entity instance transitions from the new state to the managed state.

If the entity references any related entities, these entities must be in the managed state already, or have cascade-on-persist enabled. If neither of these criteria are met, an IllegalStateException will be thrown.

See an example in the following section.

Fetching Entities by ID

If you know the unique ID of an entity object, you can use the EntityManager.find() method to retrieve it from persistent storage. The object returned from the find() method will be in the managed state.

Example:

    // make it
    Album album = new Album();
    album.setArtist(null);
    album.setName("Abbey Road");
    album.setReleaseDate(new Date(-8366400000L));

    // store it
    EntityManager em = getEntityManager();
    em.persist(album);
    em.flush();
    em.detach(album);
    assertNotNull(album.getId());

    // fetch it
    Album fetchedAlbum = em.find(Album.class, album.getId());
    assertNotSame(album, fetchedAlbum);
    assertEquals(album.toString(), fetchedAlbum.toString());

Removing Entities from Persistent Storage

To remove a persistent managed entity, pass it to the EntityManager.remove() method. As the cascade rules specify, related entities will also be removed recursively.

Once an entity has been removed and the entity manager's state has been flushed, the entity object is unmanaged and back in the new state.

@EntryPoint
public class Main {

  @Inject EntityManager em;

  void resetJpaStorage() {
    ((ErraiEntityManager) em).removeAll();
  }
}

Detaching Entity Instances from the Entity Manager

For every entity instance in the managed state, changes to the attribute values of that entity are persisted to local storage whenever the entity manager is flushed. To prevent this automatic updating from happening, you can detach an entity from the entity manager. When an instance is detached, it is not deleted. All information about it remains in persistent storage. The next time that entity is retrieved, the entity manager will create a new and separate managed instance for it.

To detach one particular object along with all related objects whose cascade rules say so, call EntityManager.detach() and pass in that object.

To detach all objects from the entity manager at once, call EntityManager.detachAll().

Testing if an Entity is in the Managed State

To check if a given object is presently managed by the entity manager, call EntityManager.contains() and pass in the object of interest.

Declaring Named Queries

Queries in JPA are written in the JPQL language. As of Errai 2.1, Errai JPA does not support all JPQL features. Most importantly, implicit and explicit joins in queries are not yet supported. Queries of the following form generally work:

SELECT et FROM EntityType et WHERE [expression with constants, named parameters and attributes of et] ORDER BY et.attr1 [ASC|DESC], et.attr2 [ASC|DESC]

Here is how to declare a JPQL query on an entity:

@NamedQuery(name="selectAlbumByName", query="SELECT a FROM Album a WHERE a.name=:name")
@Entity
public class Album {
  ... same as before ...
}

To declare more than one query on the same entity, wrap the @NamedQuery annotations in @NamedQueries like this:

@NamedQueries({
  @NamedQuery(name="selectAlbumByName", query="SELECT a FROM Album a WHERE a.name = :name"),
  @NamedQuery(name="selectAlbumsAfter", query="SELECT a FROM Album a WHERE a.releaseDate >= :startDate")
})
@Entity
public class Album {
  ... same as before ...
}

Executing Named Queries

To execute a named query, retrieve it by name and result type from the entity manager, set the values of its parameters (if any), and then call one of the execution methods getSingleResult() or getResultList().

Example:

    TypedQuery<Album> q = em.createNamedQuery("selectAlbumByName", Album.class);
    q.setParameter("name", "Let It Be");
    List<Album> fetchedAlbums = q.getResultList();

Errai Extensions to JPA Metamodel API

Wherever you obtain an instance of SingularAttribute from the metamodel API, you can down-cast it to ErraiSingularAttribute. Likewise, you can down-cast any PluralAttribute to ErraiPluralAttribute.

In either case, you can read the value of an arbitrary attribute by calling ErraiAttribute.get() and passing in the entity instance. You can set any attribute's value by calling ErraiAttribute.set(), passing in the entity instance and the new value.

In addition to get() and set(), ErraiPluralAttribute also has the createEmptyCollection() method, which creates an empty collection of the correct interface type for the given attribute.